REST API 设计最佳实践指南 – 如何用 JavaScript、Node.js 和 Express.js 构建 REST API

推广 | 阿里云爆款云服务器68元/年，2核2G限时秒杀，超高性价比，立即抢购！

                                                                                                                                                <p>过去几年里，我创建并使用过很多 API。在此过程中，我遇到过各种好的和坏的实践，也在开发和调用 API 时碰到过不少棘手的问题，但也有很多顺利的时刻。</p> 

网上有很多介绍最佳实践的文章，但在我看来，其中不少都缺乏实用性。只懂理论、没几个实例固然有一定价值，但我总是会想：在更真实的场景中，这些理论该如何落地？

简单的示例能帮助我们理解概念本身，避免过多复杂性干扰，但实际开发中事情往往没那么简单。我相信你肯定懂这种感受 😁

这就是我决定写这篇教程的原因。我把自己的所有经验（好的、坏的都有）整合到这篇通俗易懂的文章里，同时提供了可跟着操作的实战案例。最终，我们会一步步落实最佳实践，搭建出一个完整的 API。

开始前需要明确几点： 所谓”最佳实践”，并非必须严格遵守的法律或规则，而是经过时间检验、被证明有效的约定或建议。其中一些如今已成为标准，但这并不意味着你必须原封不动地照搬。

它们的核心目的是为你提供方向，帮助你从用户体验（包括调用者和开发者）、安全性、性能三个维度优化 API。

但请记住：不同项目需要不同的解决方案。有些情况下，你可能无法或不应该遵循某条约定。因此，最终需要开发者自己或与团队共同判断。

好了，废话不多说，我们开始吧！

目录

1. 示例项目介绍

2. 前置要求

3. 架构设计

4. 基础搭建

5. REST API 最佳实践

   1. 版本控制
   2. 资源命名使用复数形式
   3. 接收与返回数据采用 JSON 格式
   4. 用标准 HTTP 错误码响应
   5. 端点名称避免使用动词
   6. 关联资源分组（逻辑嵌套）
   7. 集成过滤、排序与分页
   8. 用数据缓存提升性能
   9. 良好的安全实践
   10. 完善 API 文档

6. 总结

7. 示例项目介绍